.\"
.\" Copyright (c) 2001-2021 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd JANUARY 30, 2002
.Dt MAP 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.6
.Sh NAME
.Nm MAP
.Nd agar feature-based tile map
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/map.h>
.Ed
.Sh DESCRIPTION
The
.Nm
interface implements a two-dimensional map of fixed-size tiles, which are
stacks of elements 
Element types include:
.Pp
.Bl -tag -width "MAP_ITEM_TILE " -compact
.It MAP_ITEM_TILE
Pointer to a
.Xr RG_Tile 3 .
.It MAP_ITEM_WARP
Pointer to some other node, possibly on another map.
This is commonly used by
.Xr MAP_Actor 3
objects.
.El
.Pp
Graphical elements define two displacements in pixels of the image from
the tile's origin, the
.Em centering offset
and the
.Em motion offset.
.Pp
The centering offset is typically assigned by a level designer, and the
motion offset is for animation purposes.
If the map is drawn scaled, the centering offset is scaled to the
tile size, but the motion offset is not.
.Pp
Graphical elements provide the renderer with a list of graphical transformations
that should be applied before the tile is drawn (the resulting tile is cached).
A per-element layer attribute also defines the attributed layer.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "MAP *"
.Fn MAP_New "void *parent" "const char *name"
.Pp
.Ft int
.Fn MAP_AllocNodes "MAP *map" "Uint w" "Uint h"
.Pp
.Ft void
.Fn MAP_FreeNodes "MAP *map"
.Pp
.Ft void
.Fn MAP_SetZoom "MAP *map" "int camera" "Uint factor"
.Pp
.nr nS 0
.Fn MAP_New
allocates, initializes and attaches a new map.
.Pp
.Fn MAP_AllocNodes
allocates
.Fa w
x
.Fa h
nodes, assuming that no node is currently allocated.
.Fn MAP_AllocNodes
returns 0 on success or -1 on failure.
The maximum allowable geometry is defined by
.Dv MAP_WIDTH_MAX
and
.Dv MAP_HEIGHT_MAX .
.Fn MAP_FreeNodes
releases the nodes allocated by
.Fa map .
.Pp
.Fn MAP_Resize
reallocates the nodes arrays, initializing the new nodes and
freeing the excess ones.
.Fn MAP_Resize
returns 0 on sucess or -1 on failure.
.Pp
.Fn MAP_SetZoom
sets the zoom factor for a given map view.
Actors are displayed to this scale.
.Sh NODE INITIALIZATION
.nr nS 1
.Ft void
.Fn MAP_NodeInit "MAP_Node *node"
.Pp
.Ft void
.Fn MAP_NodeDestroy "MAP *map" "MAP_Node *node"
.Pp
.Ft int
.Fn MAP_NodeLoad "MAP *map" "AG_DataSource *ds" "MAP_Node *node"
.Pp
.Ft void
.Fn MAP_NodeSave "const MAP *map" "AG_DataSource *ds" "const MAP_Node *node"
.Pp
.nr nS 0
.Fn MAP_NodeInit
initializes the
.Fa node
structure.
.Fn MAP_NodeDestroy
frees all resources allocated by
.Fa node .
.Pp
.Fn MAP_NodeLoad
loads the contents of
.Fa node
(presumed initialized and empty), from data source
.Fa ds .
.Fn MAP_NodeSave
saves the contents of
.Fa node
to
.Fa ds .
Both functions are called implicitely by the
.Fn load
and
.Fn save
operations of
.Nm .
.Sh MAP ITEMS
.nr nS 1
.Ft void
.Fn MAP_ItemInit "MAP_Item *mi"
.Pp
.Ft void
.Fn MAP_ItemDestroy "MAP *map" "MAP_Item *mi"
.Pp
.nr nS 0
.Fn MAP_ItemInit
initializes the
.Fa mi
structure.
.Fn MAP_ItemDestroy
frees all resources allocated for
.Fa mi .
.Sh NODE MANIPULATIONS
.nr nS 1
.Ft void
.Fn MAP_MoveItem "MAP *mapSrc" "MAP_Node *nodeSrc" "MAP_Item *miSrc" "MAP *mapDst" "MAP_Node *nodeDst" "int layerDst"
.Pp
.Ft "MAP_Item *"
.Fn MAP_CopyItem "const MAP_Item *miSrc" "MAP *mapDst" "MAP_Node *nodeDst" "int layerDst"
.Pp
.Ft void
.Fn MAP_DelItem "MAP *map" "MAP_Node *node" "MAP_Item *mi"
.Pp
.Ft "MAP_Item *"
.Fn MAP_TileNew "MAP *map" "MAP_Node *node" "RG_Tileset *ts" "Uint tileID"
.Pp
.Ft "MAP_Link *"
.Fn MAP_LinkNew "MAP *map" "MAP_Node *nodeDst" "const char *targetMap" "int x" "int y" "Uint8 dir"
.Pp
.nr nS 0
.Fn MAP_MoveItem
moves item
.Fa miSrc
from
.Fa nodeSrc
(of
.Fa mapSrc )
over to
.Fa nodeDst
(of
.Fa mapDst ) .
.Pp
.Fn MAP_CopyItem
inserts a copy of
.Fa miSrc
on top of
.Fa nodeDst .
The copy is associated with
.Fa layerDst
(or -1 = the source layer).
.Pp
.Fn MAP_DelItem
deletes item
.Fa mi
from
.Fa node .
.Pp
.Fn MAP_TileNew
creates a reference to the
.Xr RG_Tile 3
element identified by
.Fa tileID
in the given
.Xr RG_Tileset 3 .
.Pp
.Fn MAP_LinkNew
Creates a link to the node
.Fa x ,
.Fa y
of
.Fa targetMap .
This is the pathname of the destination map (as returned by
.Fn AG_ObjectCopyName ) .
.Sh ACTORS
.nr nS 1
.Ft void
.Fn MAP_AttachActor "MAP *map" "MAP_Actor *actor"
.Pp
.Ft void
.Fn MAP_DetachActor "MAP *map" "MAP_Actor *actor"
.Pp
.nr nS 0
.Fn MAP_AttachActor
attaches the given actor
to the map.
An object dependency is automatically created, and the
.Va map
operation of the actor is invoked.
This operation is usually responsible for inserting tiles onto the map.
.Pp
.Fn MAP_DetachActor
detaches the given actor from the map.
Any pending timer events related to the actor are cancelled, tiles
related to the actor are removed and the object dependency is removed.
.Pp
See
.Xr MAP_Actor 3
for more information.
.Sh SEE ALSO
.Xr AG_Object 3 ,
.Xr MAP_Actor 3 ,
.Xr MAP_View 3 ,
.Xr SG_Intro 3
.Sh HISTORY
The
.Nm
class first appeared in Agar 1.0.
